<!--
  ****************************************************************************
  * Copyright 2018-2024,2025 Thomas E. Dickey                                *
  * Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
  *                                                                          *
  * Permission is hereby granted, free of charge, to any person obtaining a  *
  * copy of this software and associated documentation files (the            *
  * "Software"), to deal in the Software without restriction, including      *
  * without limitation the rights to use, copy, modify, merge, publish,      *
  * distribute, distribute with modifications, sublicense, and/or sell       *
  * copies of the Software, and to permit persons to whom the Software is    *
  * furnished to do so, subject to the following conditions:                 *
  *                                                                          *
  * The above copyright notice and this permission notice shall be included  *
  * in all copies or substantial portions of the Software.                   *
  *                                                                          *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  *                                                                          *
  * Except as contained in this notice, the name(s) of the above copyright   *
  * holders shall not be used in advertising or otherwise to promote the     *
  * sale, use or other dealings in this Software without prior written       *
  * authorization.                                                           *
  ****************************************************************************
  * @Id: curs_bkgd.3x,v 1.74 2025/01/19 00:49:39 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>curs_bkgd 3x 2025-01-18 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">

</HEAD>
<BODY>
<H1 class="no-header">curs_bkgd 3x 2025-01-18 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>                    Library calls                   <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>




</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
       <STRONG>bkgdset</STRONG>,  <STRONG>wbkgdset</STRONG>,  <STRONG>bkgd</STRONG>,  <STRONG>wbkgd</STRONG>, <STRONG>getbkgd</STRONG> - manipulate background of a
       <EM>curses</EM> window of characters


</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
       <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>

       <STRONG>int</STRONG> <STRONG>bkgd(chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>wbkgd(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>

       <STRONG>void</STRONG> <STRONG>bkgdset(chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
       <STRONG>void</STRONG> <STRONG>wbkgdset(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>

       <STRONG>chtype</STRONG> <STRONG>getbkgd(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG>


</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
       Every <EM>curses</EM>  window  has  a  <EM>background</EM>  <EM>character</EM>  property:  in  the
       library's  non-wide  configuration,  it  is a <EM>curses</EM> character (<EM>chtype</EM>)
       that combines a set of attributes (and, if colors are enabled, a  color
       pair  identifier)  with  a  character  code.  When erasing (parts of) a
       window, <EM>curses</EM> replaces the erased cells with the background character.

       <EM>curses</EM> also uses the background character when writing characters to  a
       populated window.

       <STRONG>o</STRONG>   The  attribute  part  of the background character combines with all
           non-blank character cells  in  the  window,  as  populated  by  the
           <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG>  and  <STRONG><A HREF="curs_insch.3x.html">winsch(3x)</A></STRONG>  families  of functions (and those that
           call them).

       <STRONG>o</STRONG>   Both the character code and attributes of the background  character
           combine with blank character cells in the window.

       The  background character's set of attributes becomes a property of the
       character cell and move with it through any scrolling and insert/delete
       line/character  operations.   To  the  extent  possible on the terminal
       type, <EM>curses</EM> displays the attributes of the background character as the
       graphic rendition of a character cell on the display.


</PRE><H3><a name="h3-bkgd_wbkgd">bkgd, wbkgd</a></H3><PRE>
       <STRONG>bkgd</STRONG>  and  <STRONG>wbkgd</STRONG> set the background property of <STRONG>stdscr</STRONG> or the specified
       window and then apply this setting to  every  character  cell  in  that
       window.

       <STRONG>o</STRONG>   The  rendition  of every character in the window changes to the new
           background rendition.

       <STRONG>o</STRONG>   Wherever the former background character appears, it changes to the
           new background character.

       <EM>ncurses</EM>  updates  the rendition of each character cell by comparing the
       character, non-color attributes, and color pair selection.  The library
       applies  the following procedure to each cell in the window, whether or
       not it is blank.

       <STRONG>o</STRONG>   <EM>ncurses</EM> first compares  the  cell's  character  to  the  previously
           specified  background  character; if they match, <EM>ncurses</EM> writes the
           new background character to the cell.

       <STRONG>o</STRONG>   <EM>ncurses</EM> then checks whether the cell uses color; that is, its color
           pair  value  is nonzero.  If not, it simply replaces the attributes
           and color pair in the cell  with  those  from  the  new  background
           character.

       <STRONG>o</STRONG>   If  the  cell  uses color, and its background color matches that of
           the current window background, <EM>ncurses</EM> removes attributes that  may
           have  come  from the current background and adds those from the new
           background.  It finishes by setting the cell's  background  to  use
           the new window background color.

       <STRONG>o</STRONG>   If  the  cell  uses  color, and its background color does not match
           that of the current window background,  <EM>ncurses</EM>  updates  only  the
           non-color  attributes, first removing those that may have come from
           the current background, and then adding  attributes  from  the  new
           background.

       If the new background's character is non-spacing (for example, if it is
       a  control  character),  <EM>ncurses</EM>  retains   the   existing   background
       character,  except  for  one  special case: <EM>ncurses</EM> treats a background
       character code of zero (0) as a space.

       If the terminal does not support  color,  or  if  color  has  not  been
       initialized  with  <STRONG><A HREF="curs_color.3x.html">start_color(3x)</A></STRONG>,  <EM>ncurses</EM> ignores the new background
       character's color pair selection.


</PRE><H3><a name="h3-bkgdset_wbkgdset">bkgdset, wbkgdset</a></H3><PRE>
       <STRONG>bkgdset</STRONG> and  <STRONG>wbkgdset</STRONG>  manipulate  the  background  of  the  applicable
       window, without updating the character cells as <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> do; only
       future writes reflect the updated background.


</PRE><H3><a name="h3-getbkgd">getbkgd</a></H3><PRE>
       <STRONG>getbkgd</STRONG> returns the given window's  background  character,  attributes,
       and color pair as a <EM>chtype</EM>.


</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
       <STRONG>bkgdset</STRONG> and <STRONG>wbkgdset</STRONG> do not return a value.

       Functions returning an <EM>int</EM> return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success.
       In <EM>ncurses</EM>, failure occurs if

       <STRONG>o</STRONG>   the <EM>curses</EM> screen has not been initialized, or

       <STRONG>o</STRONG>   <EM>win</EM> is <EM>NULL</EM>.

       <STRONG>getbkgd</STRONG>'s return value is as described above.


</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
       Unusually, there is no <STRONG>wgetbkgd</STRONG> function; <STRONG>getbkgd</STRONG> behaves as one  would
       expect <STRONG>wgetbkgd</STRONG> to, accepting a <EM>WINDOW</EM> pointer argument.

       <STRONG>bkgd</STRONG> and <STRONG>bkgdset</STRONG> may be implemented as macros.

       X/Open  Curses  mentions that the character part of the background must
       be a single-byte value.  <EM>ncurses</EM>, like SVr4 <EM>curses</EM>,  checks  to  ensure
       that  it is, and retains the existing background character if the check
       fails.


</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
       X/Open Curses Issue 4 describes these  functions.   It  indicates  that
       <EM>bkgd</EM>,  <EM>wbkgd</EM>,  and  <EM>getbkgd</EM>  return  <EM>ERR</EM> on failure (in the case of the
       last, this value is cast to <EM>chtype</EM>), but specifies no error  conditions
       for them.

       SVr4  documentation  says  that  <EM>bkgd</EM>  and  <EM>wbkgd</EM>  return <EM>OK</EM> "or a non-
       negative integer if <EM>immedok()</EM> is set", referring to  the  return  value
       from  <EM>wrefresh</EM>,  which in SVr4 returns a count of characters written to
       the window if its <EM>immedok</EM> property is set; in <EM>ncurses</EM>, it does not.

       Neither X/Open  Curses  nor  the  SVr4  manual  pages  detail  how  the
       rendition  of  characters  in  the  window  updates  when <EM>bkgd</EM> or <EM>wbkgd</EM>
       changes the background character.  <EM>ncurses</EM>, like SVr4 <EM>curses</EM>, does  not
       (in  its  non-wide  configuration)  store  the  background  and  window
       attribute contributions to each character cell separately.


</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
       SVr3.1 (1987) introduced these functions.


</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
       <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG> describes  the  corresponding  functions  in  the  wide
       configuration of <EM>ncurses</EM>.

       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>



ncurses 6.5                       2025-01-18                     <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-bkgd_wbkgd">bkgd, wbkgd</a></li>
<li><a href="#h3-bkgdset_wbkgdset">bkgdset, wbkgdset</a></li>
<li><a href="#h3-getbkgd">getbkgd</a></li>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-HISTORY">HISTORY</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
</BODY>
</HTML>
